home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / QuickTime / QuickTime 3 Interfaces & Libs / QTDevWin / CIncludes / JManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-21  |  33.2 KB  |  1,010 lines  |  [TEXT/dosa]
  1. /*
  2.      File:        JManager.h
  3.  
  4.      Contains:    Routines that can be used to invoke the Java Virtual Machine in MRJ 
  5.  
  6.      Version:    Technology:    MRJ 2.0
  7.                  Release:    QuickTime 3.0
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __JMANAGER__
  19. #define __JMANAGER__
  20.  
  21. /*
  22.  *  Note:    If you want to use any JManger routines which use JNI or JRI functionality,
  23.  *             you must #include <jni.h> or <jri.h> before this file.
  24.  *
  25.  */
  26. #ifndef __CONDITIONALMACROS__
  27. #include <ConditionalMacros.h>
  28. #endif
  29. #ifndef __MACTYPES__
  30. #include <MacTypes.h>
  31. #endif
  32. #ifndef __FILES__
  33. #include <Files.h>
  34. #endif
  35. #ifndef __DRAG__
  36. #include <Drag.h>
  37. #endif
  38. #ifndef __QUICKDRAW__
  39. #include <Quickdraw.h>
  40. #endif
  41. #ifndef __MENUS__
  42. #include <Menus.h>
  43. #endif
  44. #ifndef __TEXTCOMMON__
  45. #include <TextCommon.h>
  46. #endif
  47.  
  48.  
  49.  
  50. #if PRAGMA_ONCE
  51. #pragma once
  52. #endif
  53.  
  54. #ifdef __cplusplus
  55. extern "C" {
  56. #endif
  57.  
  58. #if PRAGMA_IMPORT
  59. #pragma import on
  60. #endif
  61.  
  62. #if PRAGMA_STRUCT_ALIGN
  63.     #pragma options align=mac68k
  64. #elif PRAGMA_STRUCT_PACKPUSH
  65.     #pragma pack(push, 2)
  66. #elif PRAGMA_STRUCT_PACK
  67.     #pragma pack(2)
  68. #endif
  69.  
  70. #if PRAGMA_ENUM_ALWAYSINT
  71.     #pragma enumsalwaysint on
  72. #elif PRAGMA_ENUM_OPTIONS
  73.     #pragma option enum=int
  74. #elif PRAGMA_ENUM_PACK
  75.     #if __option(pack_enums)
  76.         #define PRAGMA_ENUM_PACK__JMANAGER__
  77.     #endif
  78.     #pragma options(!pack_enums)
  79. #endif
  80.  
  81.  
  82.  
  83. enum {
  84.     kJMVersion                    = 0x11000003,                    /* using Sun's 1.1 APIs, our current APIs. */
  85.     kDefaultJMTime                = 0x00000400                    /* how much time to give the JM library on "empty" events, in milliseconds. */
  86. };
  87.  
  88.  
  89. enum {
  90.     kJMVersionError                = -60000L,
  91.     kJMExceptionOccurred        = -60001L,
  92.     kJMBadClassPathError        = -60002L
  93. };
  94.  
  95. /*
  96.  *    Private data structures
  97.  *
  98.  *    JMClientData        - enough bits to reliably store a pointer to arbitrary, client-specific data. 
  99.  *    JMSessionRef        - references the entire java runtime 
  100.  *    JMTextRef            - a Text string, length, and encoding 
  101.  *    JMTextEncoding        - which encoding to use when converting in and out of Java strings.
  102.  *    JMFrameRef            - a java frame 
  103.  *    JMAWTContextRef     - a context for the AWT to request frames, process events 
  104.  *    JMAppletLocatorRef    - a device for locating, fetching, and parsing URLs that may contain applets 
  105.  *    JMAppletViewerRef    - an object that displays applets in a Frame 
  106.  */
  107. typedef void *                            JMClientData;
  108. typedef struct OpaqueJMSessionRef*         JMSessionRef;
  109. typedef struct OpaqueJMFrameRef*         JMFrameRef;
  110. typedef struct OpaqueJMTextRef*         JMTextRef;
  111. typedef struct OpaqueJMAWTContextRef*     JMAWTContextRef;
  112. typedef struct OpaqueJMAppletLocatorRef*  JMAppletLocatorRef;
  113. typedef struct OpaqueJMAppletViewerRef*  JMAppletViewerRef;
  114. typedef TextEncoding                     JMTextEncoding;
  115.  
  116. /*
  117.  * The runtime requires certain callbacks be used to communicate between
  118.  * session events and the embedding application.
  119.  *
  120.  * In general, you can pass nil as a callback and a "good" default will be used.
  121.  *
  122.  *    JMConsoleProcPtr          - redirect stderr or stdout - the message is delivered in the encoding specified when
  123.  *                                you created the session, or possibly binary data.
  124.  *    JMConsoleReadProcPtr     - take input from the user from a console or file.  The input is expected to 
  125.  *                                be in the encoding specified when you opened the session.
  126.  *    JMExitProcPtr              - called via System.exit(int), return "true" to kill the current thread,
  127.  *                                false, to cause a 'QUIT' AppleEvent to be sent to the current process,
  128.  *                                or just tear down the runtime and exit to shell immediately
  129.  * JMLowMemoryProcPtr          - This callback is available to notify the embedding application that
  130.  *                                a low memory situation has occurred so it can attempt to recover appropriately.
  131.  * JMAuthenicateURLProcPtr  - prompt the user for autentication based on the URL.  If you pass
  132.  *                                nil, JManager will prompt the user.  Return false if the user pressed cancel.
  133.  */
  134. typedef CALLBACK_API_C( void , JMConsoleProcPtr )(JMSessionRef session, const void *message, UInt32 messageLengthInBytes);
  135. typedef CALLBACK_API_C( SInt32 , JMConsoleReadProcPtr )(JMSessionRef session, void *buffer, SInt32 maxBufferLength);
  136. typedef CALLBACK_API_C( Boolean , JMExitProcPtr )(JMSessionRef session, int value);
  137. typedef CALLBACK_API_C( Boolean , JMAuthenticateURLProcPtr )(JMSessionRef session, const char *url, const char *realm, char userName[255], char password[255])/*  into C string parameters  */;
  138. typedef CALLBACK_API_C( void , JMLowMemoryProcPtr )(JMSessionRef session);
  139.  
  140. struct JMSessionCallbacks {
  141.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  142.     JMConsoleProcPtr                 fStandardOutput;            /* JM will route "stdout" to this function. */
  143.     JMConsoleProcPtr                 fStandardError;                /* JM will route "stderr" to this function. */
  144.     JMConsoleReadProcPtr             fStandardIn;                /* read from console - can be nil for default behavior (no console IO) */
  145.     JMExitProcPtr                     fExitProc;                    /* handle System.exit(int) requests */
  146.     JMAuthenticateURLProcPtr         fAuthenticateProc;            /* present basic authentication dialog */
  147.     JMLowMemoryProcPtr                 fLowMemProc;                /* Low Memory notification Proc */
  148. };
  149. typedef struct JMSessionCallbacks        JMSessionCallbacks;
  150.  
  151. enum JMVerifierOptions {
  152.     eDontCheckCode                = 0,
  153.     eCheckRemoteCode            = 1,
  154.     eCheckAllCode                = 2
  155. };
  156. typedef enum JMVerifierOptions JMVerifierOptions;
  157.  
  158.  
  159. /*
  160.  * JMRuntimeOptions is a mask that allows you to specify certain attributes
  161.  * for the runtime. Bitwise or the fields together, or use one of the "premade" entries.
  162.  * eJManager2Defaults is the factory default, and best bet to use.
  163.  */
  164.  
  165. enum JMRuntimeOptions {
  166.     eJManager2Defaults            = 0,
  167.     eUseAppHeapOnly                = (1 << 0),
  168.     eDisableJITC                = (1 << 1),
  169.     eEnableDebugger                = (1 << 2),
  170.     eDisableInternetConfig        = (1 << 3),
  171.     eInhibitClassUnloading        = (1 << 4),
  172.     eEnableProfiling            = (1 << 5),
  173.     eJManager1Compatible        = (eDisableInternetConfig | eInhibitClassUnloading)
  174. };
  175. typedef enum JMRuntimeOptions JMRuntimeOptions;
  176.  
  177.  
  178.  
  179.  
  180. /*
  181.  * Returns the version of the currently installed JManager library.
  182.  * Compare to kJMVersion.  This is the only call that doesn't
  183.  * require a session, or a reference to something that references
  184.  * a session.
  185.  */
  186. EXTERN_API_C( unsigned long )
  187. JMGetVersion                    (void);
  188.  
  189. /*
  190.  * JMOpenSession creates a new Java Runtime.  Note that JManger 2.0 doesn't set 
  191.  * security options at the time of runtime instantiation.  AppletViewer Objecs have
  192.  * seperate security attributes bound to them, and the verifier is availiable elsewhere
  193.  * as well.  The client data parameter lets a client associate an arbitgrary tagged pointer
  194.  * with the seession.
  195.  * When you create the session, you must specify the desired Text Encoding to use for
  196.  * console IO.  Usually, its OK to use "kTextEncodingMacRoman".  See TextCommon.h for the list.
  197.  */
  198. EXTERN_API_C( OSStatus )
  199. JMOpenSession                    (JMSessionRef *            session,
  200.                                  JMRuntimeOptions         runtimeOptions,
  201.                                  JMVerifierOptions         verifyMode,
  202.                                  const JMSessionCallbacks * callbacks,
  203.                                  JMTextEncoding         desiredEncoding,
  204.                                  JMClientData             data);
  205.  
  206. EXTERN_API_C( OSStatus )
  207. JMCloseSession                    (JMSessionRef             session);
  208.  
  209.  
  210. /*
  211.  * Client data getter/setter functions.
  212.  */
  213. EXTERN_API_C( OSStatus )
  214. JMGetSessionData                (JMSessionRef             session,
  215.                                  JMClientData *            data);
  216.  
  217. EXTERN_API_C( OSStatus )
  218. JMSetSessionData                (JMSessionRef             session,
  219.                                  JMClientData             data);
  220.  
  221.  
  222. /*
  223.  * Prepend the target of the FSSpec to the class path.
  224.  * If a file, .zip or other known archive file - not a .class file
  225.  */
  226. EXTERN_API_C( OSStatus )
  227. JMAddToClassPath                (JMSessionRef             session,
  228.                                  const FSSpec *            spec);
  229.  
  230.  
  231. /*
  232.  * Utility returns (client owned) null terminated handle containing "file://xxxx", or nil if fnfErr
  233.  */
  234. EXTERN_API_C( Handle )
  235. JMFSSToURL                        (JMSessionRef             session,
  236.                                  const FSSpec *            spec);
  237.  
  238.  
  239. /*
  240.  * Turns "file:///disk/file" into an FSSpec.  other handlers return paramErr
  241.  */
  242. EXTERN_API_C( OSStatus )
  243. JMURLToFSS                        (JMSessionRef             session,
  244.                                  const char *            urlString,
  245.                                  FSSpec *                spec);
  246.  
  247.  
  248. /*
  249.  * JMIdle gives time to all Java threads. Giving more time makes Java programs run faster,
  250.  * but can reduce overall system responsiveness. JMIdle will return sooner if low-level (user)
  251.  * events appear in the event queue.
  252.  */
  253. EXTERN_API_C( OSStatus )
  254. JMIdle                            (JMSessionRef             session,
  255.                                  UInt32                 jmTimeMillis);
  256.  
  257.  
  258. /*
  259.  * JMGetCurrenvEnv gives access to the underlying JRI interface, if available.
  260.  * This gives the client more control over the underlying Java runtime, without
  261.  * exposing the implementation too much.
  262.  * NOTE: JRI is deprecated; please upgrade your code to work with JNI instead.
  263.  */
  264. #ifdef JRI_H
  265. EXTERN_API_C( JRIRuntimeInstance *)
  266. JMGetJRIRuntimeInstance            (JMSessionRef             session);
  267.  
  268. #endif  /*  defined(JRI_H)  */
  269.  
  270. #ifdef JNI_H
  271. EXTERN_API_C( JRIEnv *)
  272. JMGetCurrentJRIEnv                (JMSessionRef             session);
  273.  
  274. #endif  /*  defined(JNI_H)  */
  275.  
  276. /*
  277.  * JNI is to be preferred.
  278.  */
  279. #ifdef JNI_H
  280. EXTERN_API_C( JNIEnv *)
  281. JMGetCurrentEnv                    (JMSessionRef             session);
  282.  
  283. #endif  /*  defined(JNI_H)  */
  284.  
  285. /*
  286.  * Since JManager calls reutrn jref (JRI Java references)
  287.  * you need to convert between them and JNI references (jobjects) if you're
  288.  * using JNI.  These routines facilitate that conversion.
  289.  */
  290. #if defined(JRI_H) && defined(JNI_H)
  291. EXTERN_API_C( jobject )
  292. JMJRIRefToJNIObject                (JMSessionRef             session,
  293.                                  JNIEnv *                env,
  294.                                  jref                     jriRef);
  295.  
  296. EXTERN_API_C( jref )
  297. JMJNIObjectToJRIRef                (JMSessionRef             session,
  298.                                  JNIEnv *                env,
  299.                                  jobject                 jniObject);
  300.  
  301. #endif  /*  defined(JRI_H)  &&  defined(JNI_H)  */
  302.  
  303. /*
  304.  * Java defines system-wide properties that applets can use to make queries about the
  305.  * host system. Many of these properties correspond to defaults provided by "Internet Config."
  306.  * JMPutSessionProperty can be used by a client program to modify various system-wide properties.
  307.  */
  308. EXTERN_API_C( OSStatus )
  309. JMGetSessionProperty            (JMSessionRef             session,
  310.                                  JMTextRef                 propertyName,
  311.                                  JMTextRef *            propertyValue);
  312.  
  313. EXTERN_API_C( OSStatus )
  314. JMPutSessionProperty            (JMSessionRef             session,
  315.                                  JMTextRef                 propertyName,
  316.                                  JMTextRef                 propertyValue);
  317.  
  318.  
  319. /*
  320.  * Returns a com.apple.mrj.JManager.JMSession object
  321.  */
  322. #ifdef JRI_H
  323. EXTERN_API_C( jref )
  324. JMGetSessionObject                (JMSessionRef             session);
  325.  
  326. #endif  /*  defined(JRI_H)  */
  327.  
  328. /*
  329.  * JMText: opaque object that encapsulates a string, length, and
  330.  * character encoding.  Strings passed between JManager and the
  331.  * embedding application goes through this interface.  Only the most
  332.  * rudimentary conversion routines are supplied - it is expected that
  333.  * the embedding application will most of its work in the System Script.
  334.  *
  335.  * These APIs present some questions about who actually owns the 
  336.  * JMText.  The rule is, if you created a JMTextRef, you are responsible
  337.  * for deleting it after passing it into the runtime.  If the runtime passes
  338.  * one to you, it will be deleted after the callback.
  339.  *
  340.  * If a pointer to an uninitialised JMTextRef is passed in to a routine (eg JMGetSessionProperty),
  341.  * it is assumed to have been created for the caller, and it is the callers responsibility to
  342.  * dispose of it.
  343.  *
  344.  * The encoding types are taken verbatim from the Text Encoding Converter,
  345.  * which handles the ugly backside of script conversion.
  346.  */
  347. /*
  348.  * JMNewTextRef can create from a buffer of data in the specified encoding
  349.  */
  350. EXTERN_API_C( OSStatus )
  351. JMNewTextRef                    (JMSessionRef             session,
  352.                                  JMTextRef *            textRef,
  353.                                  JMTextEncoding         encoding,
  354.                                  const void *            charBuffer,
  355.                                  UInt32                 bufferLengthInBytes);
  356.  
  357.  
  358. /*
  359.  * JMCopyTextRef clones a text ref.
  360.  */
  361. EXTERN_API_C( OSStatus )
  362. JMCopyTextRef                    (JMTextRef                 textRefSrc,
  363.                                  JMTextRef *            textRefDst);
  364.  
  365.  
  366. /*
  367.  * Disposes of a text ref passed back from the runtime, or created explicitly through JMNewTextRef
  368.  */
  369. EXTERN_API_C( OSStatus )
  370. JMDisposeTextRef                (JMTextRef                 textRef);
  371.  
  372.  
  373. /*
  374.  * Returns the text length, in characters
  375.  */
  376. EXTERN_API_C( OSStatus )
  377. JMGetTextLength                    (JMTextRef                 textRef,
  378.                                  UInt32 *                textLengthInCharacters);
  379.  
  380.  
  381. /*
  382.  * Returns the text length, in number of bytes taken in the destination encoding
  383.  */
  384. EXTERN_API_C( OSStatus )
  385. JMGetTextLengthInBytes            (JMTextRef                 textRef,
  386.                                  JMTextEncoding         dstEncoding,
  387.                                  UInt32 *                textLengthInBytes);
  388.  
  389.  
  390. /*
  391.  * Copies the specified number of characters to the destination buffer with the appropriate
  392.  * destination encoding.
  393.  */
  394. EXTERN_API_C( OSStatus )
  395. JMGetTextBytes                    (JMTextRef                 textRef,
  396.                                  JMTextEncoding         dstEncoding,
  397.                                  void *                    textBuffer,
  398.                                  UInt32                 textBufferLength,
  399.                                  UInt32 *                numCharsCopied);
  400.  
  401.  
  402. /*
  403.  * Return the JMText as a reference to a Java String.  Note that
  404.  * this is the only reference to the string - it will be collected if you don't
  405.  * hang on to it.
  406.  */
  407. #ifdef JRI_H
  408. EXTERN_API_C( jref )
  409. JMTextToJavaString                (JMTextRef                 textRef);
  410.  
  411. #endif  /*  defined(JRI_H)  */
  412.  
  413. /*
  414.  * Returns a Handle to a null terminated, "C" string in the System Script.
  415.  */
  416. EXTERN_API_C( Handle )
  417. JMTextToMacOSCStringHandle        (JMTextRef                 textRef);
  418.  
  419.  
  420.  
  421.  
  422. /*
  423.  * Proxy properties in the runtime.
  424.  *
  425.  * These will only be checked if InternetConfig isn't used to specify properties,
  426.  * or if it doesn't have the data for these.
  427.  */
  428.  
  429. struct JMProxyInfo {
  430.     Boolean                         useProxy;
  431.     char                             proxyHost[255];
  432.     UInt16                             proxyPort;
  433. };
  434. typedef struct JMProxyInfo                JMProxyInfo;
  435.  
  436. enum JMProxyType {
  437.     eHTTPProxy                    = 0,
  438.     eFirewallProxy                = 1,
  439.     eFTPProxy                    = 2
  440. };
  441. typedef enum JMProxyType JMProxyType;
  442.  
  443. EXTERN_API_C( OSStatus )
  444. JMGetProxyInfo                    (JMSessionRef             session,
  445.                                  JMProxyType             proxyType,
  446.                                  JMProxyInfo *            proxyInfo);
  447.  
  448. EXTERN_API_C( OSStatus )
  449. JMSetProxyInfo                    (JMSessionRef             session,
  450.                                  JMProxyType             proxyType,
  451.                                  const JMProxyInfo *    proxyInfo);
  452.  
  453.  
  454. /*
  455.  * Security - JManager 2.0 security is handled on a per-applet basis.
  456.  * There are some security settings that are inherited from InternetConfig
  457.  * (Proxy Servers) but the verifier can now be enabled and disabled.
  458.  */
  459. EXTERN_API_C( OSStatus )
  460. JMGetVerifyMode                    (JMSessionRef             session,
  461.                                  JMVerifierOptions *    verifierOptions);
  462.  
  463. EXTERN_API_C( OSStatus )
  464. JMSetVerifyMode                    (JMSessionRef             session,
  465.                                  JMVerifierOptions         verifierOptions);
  466.  
  467.  
  468.  
  469.  
  470. /*
  471.  * The basic unit of AWT interaction is the JMFrame.  A JMFrame is bound to top level
  472.  * awt Frame, Window, or Dialog.  When a user event occurs for a MacOS window, the event is passed
  473.  * to the corrosponding frame object.  Similarly, when an AWT event occurs that requires the
  474.  * Mac OS Window to change, a callback is made.  JManager 1.x bound the frame to the window through
  475.  * a callback to set and restore the windows GrafPort.  In JManager 2.0, a GrafPort, Offset, and 
  476.  * ClipRgn are specified up front - changes in visibility and structure require that these be re-set.
  477.  * This enables support for the JavaSoft DrawingSurface API - and also improves graphics performance.
  478.  * You should reset the graphics attributes anytime the visiblity changes, like when scrolling.
  479.  * You should also set it initially when the AWTContext requests the frame.
  480.  * At various times, JM will call back to the client to register a new JMFrame, 
  481.  * indicating the frame type.  The client should take the following steps:
  482.  *
  483.  *    o    Create a new invisible window of the specified type
  484.  *    o    Fill in the callbacks parameter with function pointers
  485.  *    o    Do something to bind the frame to the window (like stuff the WindowPtr in the JMClientData of the frame)
  486.  *    o    Register the visiblity parameters (GrafPtr, etc) with the frame
  487.  */
  488.  
  489. enum ReorderRequest {
  490.     eBringToFront                = 0,                            /* bring the window to front */
  491.     eSendToBack                    = 1,                            /* send the window to back */
  492.     eSendBehindFront            = 2                                /* send the window behind the front window */
  493. };
  494. typedef enum ReorderRequest ReorderRequest;
  495.  
  496. typedef CALLBACK_API_C( void , JMSetFrameSizeProcPtr )(JMFrameRef frame, const Rect *newBounds);
  497. typedef CALLBACK_API_C( void , JMFrameInvalRectProcPtr )(JMFrameRef frame, const Rect *r);
  498. typedef CALLBACK_API_C( void , JMFrameShowHideProcPtr )(JMFrameRef frame, Boolean showFrameRequested);
  499. typedef CALLBACK_API_C( void , JMSetTitleProcPtr )(JMFrameRef frame, JMTextRef title);
  500. typedef CALLBACK_API_C( void , JMCheckUpdateProcPtr )(JMFrameRef frame);
  501. typedef CALLBACK_API_C( void , JMReorderFrame )(JMFrameRef frame, ReorderRequest theRequest);
  502. typedef CALLBACK_API_C( void , JMSetResizeable )(JMFrameRef frame, Boolean resizeable);
  503.  
  504. struct JMFrameCallbacks {
  505.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  506.     JMSetFrameSizeProcPtr             fSetFrameSize;
  507.     JMFrameInvalRectProcPtr         fInvalRect;
  508.     JMFrameShowHideProcPtr             fShowHide;
  509.     JMSetTitleProcPtr                 fSetTitle;
  510.     JMCheckUpdateProcPtr             fCheckUpdate;
  511.     JMReorderFrame                     fReorderFrame;
  512.     JMSetResizeable                 fSetResizeable;
  513. };
  514. typedef struct JMFrameCallbacks            JMFrameCallbacks;
  515. EXTERN_API_C( OSStatus )
  516. JMSetFrameVisibility            (JMFrameRef             frame,
  517.                                  GrafPtr                 famePort,
  518.                                  Point                     frameOrigin,
  519.                                  RgnHandle                 frameClip);
  520.  
  521. EXTERN_API_C( OSStatus )
  522. JMGetFrameData                    (JMFrameRef             frame,
  523.                                  JMClientData *            data);
  524.  
  525. EXTERN_API_C( OSStatus )
  526. JMSetFrameData                    (JMFrameRef             frame,
  527.                                  JMClientData             data);
  528.  
  529. EXTERN_API_C( OSStatus )
  530. JMGetFrameSize                    (JMFrameRef             frame,
  531.                                  Rect *                    result);
  532.  
  533. /* note that the top left indicates the "global" position of this frame */
  534. /* use this to update the frame position when it gets moved */
  535. EXTERN_API_C( OSStatus )
  536. JMSetFrameSize                    (JMFrameRef             frame,
  537.                                  const Rect *            newSize);
  538.  
  539. /*
  540.  * Dispatch a particular event to an embedded frame
  541.  */
  542. EXTERN_API_C( OSStatus )
  543. JMFrameClick                    (JMFrameRef             frame,
  544.                                  Point                     localPos,
  545.                                  short                     modifiers);
  546.  
  547. EXTERN_API_C( OSStatus )
  548. JMFrameKey                        (JMFrameRef             frame,
  549.                                  char                     asciiChar,
  550.                                  char                     keyCode,
  551.                                  short                     modifiers);
  552.  
  553. EXTERN_API_C( OSStatus )
  554. JMFrameKeyRelease                (JMFrameRef             frame,
  555.                                  char                     asciiChar,
  556.                                  char                     keyCode,
  557.                                  short                     modifiers);
  558.  
  559. EXTERN_API_C( OSStatus )
  560. JMFrameUpdate                    (JMFrameRef             frame,
  561.                                  RgnHandle                 updateRgn);
  562.  
  563. EXTERN_API_C( OSStatus )
  564. JMFrameActivate                    (JMFrameRef             frame,
  565.                                  Boolean                 activate);
  566.  
  567. EXTERN_API_C( OSStatus )
  568. JMFrameResume                    (JMFrameRef             frame,
  569.                                  Boolean                 resume);
  570.  
  571. EXTERN_API_C( OSStatus )
  572. JMFrameMouseOver                (JMFrameRef             frame,
  573.                                  Point                     localPos,
  574.                                  short                     modifiers);
  575.  
  576. EXTERN_API_C( OSStatus )
  577. JMFrameShowHide                    (JMFrameRef             frame,
  578.                                  Boolean                 showFrame);
  579.  
  580. EXTERN_API_C( OSStatus )
  581. JMFrameGoAway                    (JMFrameRef             frame);
  582.  
  583. EXTERN_API_C( JMAWTContextRef )
  584. JMGetFrameContext                (JMFrameRef             frame);
  585.  
  586. EXTERN_API_C( OSStatus )
  587. JMFrameDragTracking                (JMFrameRef             frame,
  588.                                  DragTrackingMessage     message,
  589.                                  DragReference             theDragRef);
  590.  
  591. EXTERN_API_C( OSStatus )
  592. JMFrameDragReceive                (JMFrameRef             frame,
  593.                                  DragReference             theDragRef);
  594.  
  595. #ifdef JRI_H
  596. /* 
  597.  * returns the java.awt.Frame for this frame 
  598. */
  599. EXTERN_API_C( jref )
  600. JMGetAWTFrameObject                (JMFrameRef             frame);
  601.  
  602. /* 
  603.  * returns the com.apple.mrj.JManager.JMFrame for this frame 
  604.  */
  605. EXTERN_API_C( jref )
  606. JMGetJMFrameObject                (JMFrameRef             frame);
  607.  
  608. #endif  /*  defined(JRI_H)  */
  609.  
  610. /*
  611.  * Window types
  612.  */
  613.  
  614. enum JMFrameKind {
  615.     eBorderlessModelessWindowFrame = 0,
  616.     eModelessWindowFrame        = 1,
  617.     eModalWindowFrame            = 2,
  618.     eModelessDialogFrame        = 3
  619. };
  620. typedef enum JMFrameKind JMFrameKind;
  621.  
  622.  
  623.  
  624.  
  625. /* JMAWTContext -
  626.  * To create a top level frame, you must use a JMAWTContext object.
  627.  * The JMAWTContext provides a context for the AWT to request frames.
  628.  * A AWTContext has a threadgroup associated with it - all events and processing occurs
  629.  * there.  When you create one, it is quiescent, you must call resume before it begins executing.
  630.  */
  631. typedef CALLBACK_API_C( OSStatus , JMRequestFrameProcPtr )(JMAWTContextRef context, JMFrameRef newFrame, JMFrameKind kind, const Rect *initialBounds, Boolean resizeable, JMFrameCallbacks *callbacks);
  632. typedef CALLBACK_API_C( OSStatus , JMReleaseFrameProcPtr )(JMAWTContextRef context, JMFrameRef oldFrame);
  633. typedef CALLBACK_API_C( SInt16 , JMUniqueMenuIDProcPtr )(JMAWTContextRef context, Boolean isSubmenu);
  634. typedef CALLBACK_API_C( void , JMExceptionOccurredProcPtr )(JMAWTContextRef context, JMTextRef exceptionName, JMTextRef exceptionMsg, JMTextRef stackTrace);
  635.  
  636. struct JMAWTContextCallbacks {
  637.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  638.     JMRequestFrameProcPtr             fRequestFrame;                /* a new frame is being created. */
  639.     JMReleaseFrameProcPtr             fReleaseFrame;                /* an existing frame is being destroyed. */
  640.     JMUniqueMenuIDProcPtr             fUniqueMenuID;                /* a new menu will be created with this id. */
  641.     JMExceptionOccurredProcPtr         fExceptionOccurred;            /* just some notification that some recent operation caused an exception.  You can't do anything really from here. */
  642. };
  643. typedef struct JMAWTContextCallbacks    JMAWTContextCallbacks;
  644. EXTERN_API_C( OSStatus )
  645. JMNewAWTContext                    (JMAWTContextRef *        context,
  646.                                  JMSessionRef             session,
  647.                                  const JMAWTContextCallbacks * callbacks,
  648.                                  JMClientData             data);
  649.  
  650. EXTERN_API_C( OSStatus )
  651. JMDisposeAWTContext                (JMAWTContextRef         context);
  652.  
  653. EXTERN_API_C( OSStatus )
  654. JMGetAWTContextData                (JMAWTContextRef         context,
  655.                                  JMClientData *            data);
  656.  
  657. EXTERN_API_C( OSStatus )
  658. JMSetAWTContextData                (JMAWTContextRef         context,
  659.                                  JMClientData             data);
  660.  
  661. EXTERN_API_C( OSStatus )
  662. JMCountAWTContextFrames            (JMAWTContextRef         context,
  663.                                  UInt32 *                frameCount);
  664.  
  665. EXTERN_API_C( OSStatus )
  666. JMGetAWTContextFrame            (JMAWTContextRef         context,
  667.                                  UInt32                 frameIndex,
  668.                                  JMFrameRef *            frame);
  669.  
  670. EXTERN_API_C( OSStatus )
  671. JMMenuSelected                    (JMAWTContextRef         context,
  672.                                  MenuHandle             hMenu,
  673.                                  short                     menuItem);
  674.  
  675. #ifdef JRI_H
  676. /*
  677.  * JRI Access APIs
  678.  */
  679. EXTERN_API_C( OSStatus )
  680. JMExecMethodInContext            (JMAWTContextRef         context,
  681.                                  jref                     objref,
  682.                                  JRIMethodID             methodID,
  683.                                  UInt32                 argCount,
  684.                                  JRIValue                 args[]);
  685.  
  686. EXTERN_API_C( OSStatus )
  687. JMExecStaticMethodInContext        (JMAWTContextRef         context,
  688.                                  JRIClassID             classID,
  689.                                  JRIMethodID             methodID,
  690.                                  UInt32                 argCount,
  691.                                  JRIValue                 args[]);
  692.  
  693. #endif  /*  defined(JRI_H)  */
  694.  
  695. #ifdef JNI_H
  696. /*
  697.  * JNI Access APIs
  698.  * Note that you must pass the JNIEnv to these as well.
  699.  */
  700. EXTERN_API_C( OSStatus )
  701. JMExecJNIMethodInContext        (JMAWTContextRef         context,
  702.                                  JNIEnv *                env,
  703.                                  jobject                 objref,
  704.                                  jmethodID                 methodID,
  705.                                  UInt32                 argCount,
  706.                                  jvalue                 args[]);
  707.  
  708. EXTERN_API_C( OSStatus )
  709. JMExecJNIStaticMethodInContext    (JMAWTContextRef         context,
  710.                                  JNIEnv *                env,
  711.                                  jclass                 classID,
  712.                                  jmethodID                 methodID,
  713.                                  UInt32                 argCount,
  714.                                  jvalue                 args[]);
  715.  
  716. /*
  717.  * return a com.apple.jmanager.AWTContext
  718.  */
  719. EXTERN_API_C( jref )
  720. JMGetAwtContextObject            (JMAWTContextRef         context);
  721.  
  722. #endif  /*  defined(JNI_H)  */
  723.  
  724.  
  725.  
  726.  
  727. /**
  728.  * JMAppletLocator - Since Java applets are always referenced by a Uniform Resource Locator
  729.  * (see RFC 1737, http://www.w3.org/pub/WWW/Addressing/rfc1738.txt), we provide an object
  730.  * that encapsulates the information about a set of applets. A JMAppletLocator is built
  731.  * by providing a base URL, which must point at a valid HTML document containing applet
  732.  * tags. To save a network transaction, the contents of the document may be passed optionally. 
  733.  *
  734.  * You can also use a JMLocatorInfoBlock for a synchronous resolution of the applet,
  735.  * assuming that you already have the info for the tag.
  736.  */
  737.  
  738. enum JMLocatorErrors {
  739.     eLocatorNoErr                = 0,                            /* the html was retrieved successfully*/
  740.     eHostNotFound                = 1,                            /* the host specified by the url could not be found*/
  741.     eFileNotFound                = 2,                            /* the file could not be found on the host*/
  742.     eLocatorTimeout                = 3,                            /* a timeout occurred retrieving the html text*/
  743.     eLocatorKilled                = 4                                /* in response to a JMDisposeAppletLocator before it has completed*/
  744. };
  745. typedef enum JMLocatorErrors JMLocatorErrors;
  746.  
  747. typedef CALLBACK_API_C( void , JMFetchCompleted )(JMAppletLocatorRef ref, JMLocatorErrors status);
  748.  
  749. struct JMAppletLocatorCallbacks {
  750.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  751.     JMFetchCompleted                 fCompleted;                    /* called when the html has been completely fetched */
  752. };
  753. typedef struct JMAppletLocatorCallbacks    JMAppletLocatorCallbacks;
  754. /*
  755.  * These structures are used to pass pre-parsed parameter
  756.  * tags to the AppletLocator.  Implies synchronous semantics.
  757.  */
  758.  
  759.  
  760. struct JMLIBOptionalParams {
  761.     JMTextRef                         fParamName;                    /* could be from a <parameter name=foo value=bar> or "zipbase", etc */
  762.     JMTextRef                         fParamValue;                /* the value of this optional tag */
  763. };
  764. typedef struct JMLIBOptionalParams        JMLIBOptionalParams;
  765.  
  766. struct JMLocatorInfoBlock {
  767.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  768.  
  769.                                                                 /* These are required to be present and not nil */
  770.  
  771.     JMTextRef                         fBaseURL;                    /* the URL of this applet's host page */
  772.     JMTextRef                         fAppletCode;                /* code= parameter */
  773.     short                             fWidth;                        /* width= parameter */
  774.     short                             fHeight;                    /* height= parameter */
  775.  
  776.  
  777.                                                                 /* These are optional parameters */
  778.     int                             fOptionalParameterCount;    /* how many in this array */
  779.     JMLIBOptionalParams *            fParams;                    /* pointer to an array of these (points to first element) */
  780. };
  781. typedef struct JMLocatorInfoBlock        JMLocatorInfoBlock;
  782. EXTERN_API_C( OSStatus )
  783. JMNewAppletLocator                (JMAppletLocatorRef *    locatorRef,
  784.                                  JMSessionRef             session,
  785.                                  const JMAppletLocatorCallbacks * callbacks,
  786.                                  JMTextRef                 url,
  787.                                  JMTextRef                 htmlText,
  788.                                  JMClientData             data);
  789.  
  790. EXTERN_API_C( OSStatus )
  791. JMNewAppletLocatorFromInfo        (JMAppletLocatorRef *    locatorRef,
  792.                                  JMSessionRef             session,
  793.                                  const JMLocatorInfoBlock * info,
  794.                                  JMClientData             data);
  795.  
  796. EXTERN_API_C( OSStatus )
  797. JMDisposeAppletLocator            (JMAppletLocatorRef     locatorRef);
  798.  
  799. EXTERN_API_C( OSStatus )
  800. JMGetAppletLocatorData            (JMAppletLocatorRef     locatorRef,
  801.                                  JMClientData *            data);
  802.  
  803. EXTERN_API_C( OSStatus )
  804. JMSetAppletLocatorData            (JMAppletLocatorRef     locatorRef,
  805.                                  JMClientData             data);
  806.  
  807. EXTERN_API_C( OSStatus )
  808. JMCountApplets                    (JMAppletLocatorRef     locatorRef,
  809.                                  UInt32 *                appletCount);
  810.  
  811. EXTERN_API_C( OSStatus )
  812. JMGetAppletDimensions            (JMAppletLocatorRef     locatorRef,
  813.                                  UInt32                 appletIndex,
  814.                                  UInt32 *                width,
  815.                                  UInt32 *                height);
  816.  
  817. EXTERN_API_C( OSStatus )
  818. JMGetAppletTag                    (JMAppletLocatorRef     locatorRef,
  819.                                  UInt32                 appletIndex,
  820.                                  JMTextRef *            tagRef);
  821.  
  822. EXTERN_API_C( OSStatus )
  823. JMGetAppletName                    (JMAppletLocatorRef     locatorRef,
  824.                                  UInt32                 appletIndex,
  825.                                  JMTextRef *            nameRef);
  826.  
  827.  
  828. /*
  829.  * JMAppletViewer - Applets are instantiated, one by one, by specifying a JMAppletLocator and
  830.  * a zero-based index (Macintosh API's usually use one-based indexing, the Java language
  831.  * uses zero, however.). The resulting applet is encapsulated in a JMAppletViewer object. 
  832.  * Since applets can have one or more visible areas to draw in, one or more JMFrame objects
  833.  * may be requested while the viewer is being created, or at a later time, thus the client
  834.  * must provide callbacks to satisfy these requests.
  835.  *
  836.  * The window name for the ShowDocument callback is one of:
  837.  *   _self        show in current frame
  838.  *   _parent    show in parent frame
  839.  *   _top        show in top-most frame
  840.  *   _blank        show in new unnamed top-level window
  841.  *   <other>    show in new top-level window named <other> 
  842.  */
  843. typedef CALLBACK_API_C( void , JMShowDocumentProcPtr )(JMAppletViewerRef viewer, JMTextRef urlString, JMTextRef windowName);
  844. typedef CALLBACK_API_C( void , JMSetStatusMsgProcPtr )(JMAppletViewerRef viewer, JMTextRef statusMsg);
  845.  
  846. struct JMAppletViewerCallbacks {
  847.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  848.     JMShowDocumentProcPtr             fShowDocument;                /* go to a url, optionally in a new window */
  849.     JMSetStatusMsgProcPtr             fSetStatusMsg;                /* applet changed status message */
  850. };
  851. typedef struct JMAppletViewerCallbacks    JMAppletViewerCallbacks;
  852. /*
  853.  * NEW: per-applet security settings
  854.  * Previously, these settings were attached to the session.
  855.  * JManager 2.0 allows them to be attached to each viewer.
  856.  */
  857.  
  858. enum JMNetworkSecurityOptions {
  859.     eNoNetworkAccess            = 0,
  860.     eAppletHostAccess            = 1,
  861.     eUnrestrictedAccess            = 2
  862. };
  863. typedef enum JMNetworkSecurityOptions JMNetworkSecurityOptions;
  864.  
  865.  
  866. enum JMFileSystemOptions {
  867.     eNoFSAccess                    = 0,
  868.     eLocalAppletAccess            = 1,
  869.     eAllFSAccess                = 2
  870. };
  871. typedef enum JMFileSystemOptions JMFileSystemOptions;
  872.  
  873. /*
  874.  * Lists of packages are comma separated,
  875.  * the default for mrj.security.system.access is
  876.  * "sun,netscape,com.apple".
  877.  */
  878.  
  879.  
  880. struct JMAppletSecurity {
  881.     UInt32                             fVersion;                    /* should be set to kJMVersion */
  882.     JMNetworkSecurityOptions         fNetworkSecurity;            /* can this applet access network resources */
  883.     JMFileSystemOptions             fFileSystemSecurity;        /* can this applet access network resources */
  884.  
  885.     Boolean                         fRestrictSystemAccess;        /* restrict access to system packages (com.apple.*, sun.*, netscape.*) also found in the property "mrj.security.system.access" */
  886.     Boolean                         fRestrictSystemDefine;        /* restrict classes from loading system packages (com.apple.*, sun.*, netscape.*) also found in the property "mrj.security.system.define" */
  887.  
  888.     Boolean                         fRestrictApplicationAccess;    /* restrict access to application packages found in the property "mrj.security.application.access" */
  889.     Boolean                         fRestrictApplicationDefine;    /* restrict access to application packages found in the property "mrj.security.application.access" */
  890. };
  891. typedef struct JMAppletSecurity            JMAppletSecurity;
  892. /*
  893.  * AppletViewer methods
  894.  */
  895. EXTERN_API_C( OSStatus )
  896. JMNewAppletViewer                (JMAppletViewerRef *    viewer,
  897.                                  JMAWTContextRef         context,
  898.                                  JMAppletLocatorRef     locatorRef,
  899.                                  UInt32                 appletIndex,
  900.                                  const JMAppletSecurity * security,
  901.                                  const JMAppletViewerCallbacks * callbacks,
  902.                                  JMClientData             data);
  903.  
  904. EXTERN_API_C( OSStatus )
  905. JMDisposeAppletViewer            (JMAppletViewerRef         viewer);
  906.  
  907. EXTERN_API_C( OSStatus )
  908. JMGetAppletViewerData            (JMAppletViewerRef         viewer,
  909.                                  JMClientData *            data);
  910.  
  911. EXTERN_API_C( OSStatus )
  912. JMSetAppletViewerData            (JMAppletViewerRef         viewer,
  913.                                  JMClientData             data);
  914.  
  915.  
  916. /*
  917.  * You can change the applet security on the fly
  918.  */
  919. EXTERN_API_C( OSStatus )
  920. JMGetAppletViewerSecurity        (JMAppletViewerRef         viewer,
  921.                                  JMAppletSecurity *        data);
  922.  
  923. EXTERN_API_C( OSStatus )
  924. JMSetAppletViewerSecurity        (JMAppletViewerRef         viewer,
  925.                                  const JMAppletSecurity * data);
  926.  
  927.  
  928. /*
  929.  * JMReloadApplet reloads viewer's applet from the source.
  930.  * JMRestartApplet reinstantiates the applet without reloading.
  931.  */
  932. EXTERN_API_C( OSStatus )
  933. JMReloadApplet                    (JMAppletViewerRef         viewer);
  934.  
  935. EXTERN_API_C( OSStatus )
  936. JMRestartApplet                    (JMAppletViewerRef         viewer);
  937.  
  938.  
  939. /*
  940.  * JMSuspendApplet tells the Java thread scheduler to stop executing the viewer's applet.
  941.  * JMResumeApplet resumes execution of the viewer's applet.
  942.  */
  943. EXTERN_API_C( OSStatus )
  944. JMSuspendApplet                    (JMAppletViewerRef         viewer);
  945.  
  946. EXTERN_API_C( OSStatus )
  947. JMResumeApplet                    (JMAppletViewerRef         viewer);
  948.  
  949.  
  950. /* 
  951.  * To get back to the JMAppletViewerRef instance from whence a frame came,
  952.  * as well as the ultimate frame parent (the one created _for_ the applet viewer)
  953.  */
  954. EXTERN_API_C( OSStatus )
  955. JMGetFrameViewer                (JMFrameRef             frame,
  956.                                  JMAppletViewerRef *    viewer,
  957.                                  JMFrameRef *            parentFrame);
  958.  
  959. /*
  960.  * To get a ref back to the Frame that was created for this JMAppletViewerRef
  961.  */
  962. EXTERN_API_C( OSStatus )
  963. JMGetViewerFrame                (JMAppletViewerRef         viewer,
  964.                                  JMFrameRef *            frame);
  965.  
  966. #ifdef JRI_H
  967. /*
  968.  * To get the ref of the com.apple.mrj.JManager.JMAppletViewer java object
  969.  */
  970. EXTERN_API_C( jref )
  971. JMGetAppletViewerObject            (JMAppletViewerRef         viewer);
  972.  
  973. /*
  974.  * To get the ref of the java.applet.Applet itself
  975.  */
  976. EXTERN_API_C( jref )
  977. JMGetAppletObject                (JMAppletViewerRef         viewer);
  978.  
  979. #endif  /*  defined(JRI_H)  */
  980.  
  981.  
  982. #if PRAGMA_ENUM_ALWAYSINT
  983.     #pragma enumsalwaysint reset
  984. #elif PRAGMA_ENUM_OPTIONS
  985.     #pragma option enum=reset
  986. #elif defined(PRAGMA_ENUM_PACK__JMANAGER__)
  987.     #pragma options(pack_enums)
  988. #endif
  989.  
  990. #if PRAGMA_STRUCT_ALIGN
  991.     #pragma options align=reset
  992. #elif PRAGMA_STRUCT_PACKPUSH
  993.     #pragma pack(pop)
  994. #elif PRAGMA_STRUCT_PACK
  995.     #pragma pack()
  996. #endif
  997.  
  998. #ifdef PRAGMA_IMPORT_OFF
  999. #pragma import off
  1000. #elif PRAGMA_IMPORT
  1001. #pragma import reset
  1002. #endif
  1003.  
  1004. #ifdef __cplusplus
  1005. }
  1006. #endif
  1007.  
  1008. #endif /* __JMANAGER__ */
  1009.  
  1010.